home *** CD-ROM | disk | FTP | other *** search
/ BCI NET 2 / BCI NET 2.iso / archives / programming / libraries / maestix37_20.lha / Maestix / maestix-e.adoc < prev    next >
Encoding:
Text File  |  1995-03-16  |  10.1 KB  |  382 lines
  1. TABLE OF CONTENTS
  2.  
  3. (V35) maestix.library/AllocMaestro
  4. (V36) maestix.library/FlushReceive
  5. (V36) maestix.library/FlushTransmit
  6. (V35) maestix.library/FreeMaestro
  7. (V35) maestix.library/GetStatus
  8. (V35) maestix.library/ReceiveData
  9. (V35) maestix.library/SetMaestro
  10. (V35) maestix.library/TransmitData
  11.  
  12. maestix.library/AllocMaestro                     maestix.library/AllocMaestro
  13.  
  14.    NAME
  15.     AllocMaestro -- Allocates the Maestro soundcard (V35)
  16.  
  17.    SYNOPSIS
  18.     ^MaestroBase = AllocMaestro (^Tags)
  19.         D0.l                      A0.l
  20.  
  21.    FUNCTION
  22.     This function allocates the Maestro soundcard and gives
  23.     exclusive access to the client.
  24.  
  25.     The default settings after AllocMaestro() are:
  26.  
  27.         Input is INPUT_STD,
  28.         Output is OUTPUT_BYPASS,
  29.         Studio mode is turned off,
  30.         Copy protection is turned off,
  31.         Emphasis is turned off,
  32.         Source is DAT,
  33.         Rate is 48kHz,
  34.         Validity is true,
  35.         the UDBs are reset.
  36.  
  37.    INPUTS
  38.     Tags            Reserved for future options. Currently always
  39.             NULL or a pointer to TAG_DONE.
  40.  
  41.    RESULTS
  42.     MaestroBase     Pointer to the MaestroBaseStruct (private) or
  43.             NULL, if the card has already been allocated
  44.             or is not present.
  45.  
  46.    NOTES
  47.     This function must be used from DOS process only!
  48.  
  49.    SEE ALSO
  50.     FreeMaestro()
  51.  
  52.    BUGS
  53.     This function cannot prevent the MacroSystem programs (MaestroBR
  54.     and Samplitude) from using Maestro, too.
  55.  
  56.     This function tries to detect if such a program is currently
  57.     using the card, and does not allow a second allocation. But
  58.     this try may fail, so be aware! Since some old Maestix failed
  59.     even in the case the card was not allocated, this test was
  60.     removed in V37. Use AllocMstx and FreeMstx to avoid this
  61.     problem.
  62.  
  63. maestix.library/FlushReceive                     maestix.library/FlushReceive
  64.  
  65.    NAME
  66.     FlushReceive -- Stops receiver and replies all messages (V36)
  67.  
  68.    SYNOPSIS
  69.     FlushReceive (^MaestroBase)
  70.                A0.l
  71.  
  72.    FUNCTION
  73.     This function stops the receiver.
  74.  
  75.     All messages sent to Maestix by ReceiveData() are replied.
  76.  
  77.    INPUTS
  78.     MaestroBase     Pointer to MaestroBaseStruct from AllocMaestro().
  79.  
  80.    RESULTS
  81.  
  82.    NOTES
  83.  
  84.    SEE ALSO
  85.     FlushTransmit(), ReceiveData()
  86.  
  87.    BUGS
  88.  
  89. maestix.library/FlushTransmit                   maestix.library/FlushTransmit
  90.  
  91.    NAME
  92.     FlushTransmit -- Stops transmission and replies all messages (V36)
  93.  
  94.    SYNOPSIS
  95.     FlushTransmit (^MaestroBase)
  96.                A0.l
  97.  
  98.    FUNCTION
  99.     This function stops the transmitter.
  100.  
  101.     All messages sent to Maestix by TransmitData() are replied.
  102.  
  103.    INPUTS
  104.     MaestroBase     Pointer to MaestroBaseStruct from AllocMaestro().
  105.  
  106.    RESULTS
  107.  
  108.    NOTES
  109.  
  110.    SEE ALSO
  111.     FlushReceive(), TransmitData()
  112.  
  113.    BUGS
  114.  
  115. maestix.library/FreeMaestro                       maestix.library/FreeMaestro
  116.  
  117.    NAME
  118.     FreeMaestro -- Frees the Maestro soundcard (V35)
  119.  
  120.    SYNOPSIS
  121.     FreeMaestro (^MaestroBase)
  122.              A0.l
  123.  
  124.    FUNCTION
  125.     The client must use this function to free the Maestro when he
  126.     does not need it any more.
  127.  
  128.     All messages previously sent to Maestix will be replied. The
  129.     FIFOs are cleared, the card is reset and switches to bypass
  130.     mode.
  131.  
  132.    INPUTS
  133.     MaestroBase     Pointer to MaestroBaseStruct from AllocMaestro().
  134.  
  135.    RESULTS
  136.  
  137.    NOTES
  138.     This function must be used from DOS process only!
  139.  
  140.    SEE ALSO
  141.     AllocMaestro()
  142.  
  143.    BUGS
  144.  
  145. maestix.library/GetStatus                           maestix.library/GetStatus
  146.  
  147.    NAME
  148.     GetStatus -- Returns the current card status (V35)
  149.  
  150.    SYNOPSIS
  151.     Status = GetStatus (^MaestroBase,info type)
  152.      D0.l                    A0.l      D0.l
  153.  
  154.    FUNCTION
  155.     The status fitting to the info type will be returned.
  156.  
  157.    INPUTS
  158.     MaestroBase     Pointer to MaestroBaseStruct from AllocMaestro().
  159.     info type       Type code (MSTAT_...) of the status value that
  160.             should be returned.
  161.  
  162.    RESULTS
  163.     Status          The result of the status query.
  164.  
  165.    NOTES
  166.     The following info types are existing:
  167.  
  168.     MSTAT_TFIFO     Status of transmitter FIFO
  169.              - FIFO_Off     -> transmitter is off
  170.              - FIFO_Running -> transmission is running
  171.              - FIFO_Error   -> an error occured since
  172.                        last query
  173.  
  174.     MSTAT_RFIFO     Status of receiver FIFO
  175.              - FIFO_Off     -> receiver is off
  176.              - FIFO_Running -> receiver is running
  177.              - FIFO_Error   -> an error occured since
  178.                        last query
  179.  
  180.     MSTAT_Signal    checks the signal at the current INPUT.
  181.             FALSE if there is no signal (BOOL).
  182.  
  183.     MSTAT_Emphasis  returns TRUE if the input signal has been
  184.             recorded using emphasis. (BOOL)
  185.  
  186.     MSTAT_DATsrc    returns TRUE if the data source is a DAT
  187.             or DCC recorder. (BOOL)
  188.  
  189.     MSTAT_CopyProh  returns TRUE if copy protection is requested
  190.             from source. It is not possible to detect
  191.             if it is an original or a copy! (BOOL)
  192.  
  193.     MSTAT_Rate      returns input rate (ULONG).
  194.  
  195.     MSTAT_UDB       [V37] returns the current UDBs (UBYTE).
  196.  
  197.    SEE ALSO
  198.  
  199.    BUGS
  200.  
  201. maestix.library/ReceiveData                       maestix.library/ReceiveData
  202.  
  203.    NAME
  204.     ReceiveData -- Receives data into a message (V35)
  205.  
  206.    SYNOPSIS
  207.     ReceiveData (^MaestroBase, ^DataMessage)
  208.             A0.l           A1.l
  209.  
  210.    FUNCTION
  211.     The client has to fill out a DataMessage structure with a
  212.     reply port, a pointer to a data buffer and the size of this
  213.     buffer.
  214.  
  215.     This message is queued internally. If the receiver has not
  216.     been started yet, this function will activate it.
  217.  
  218.     The buffer space get filled with the incoming data and will
  219.     be replied to the declared reply port when the space has been
  220.     filled completely.
  221.  
  222.     If there are no more messages in the queue, the receiver
  223.     will be stopped automatically, and an error is reported.
  224.  
  225.     The buffer is filled with signed words. The first word always
  226.     belongs to the left channel, the second to the right, and so
  227.     on.
  228.  
  229.    INPUTS
  230.     MaestroBase     Pointer to MaestroBase Struct from AllocMaestro().
  231.     Message         Pointer to a system message with a pointer to
  232.             a buffer space for incoming data.
  233.  
  234.    RESULTS
  235.  
  236.    NOTES
  237.     The buffer space must be public memory. Its address must be
  238.     longword aligned and its length must be aligned to 1024.
  239.  
  240.    SEE ALSO
  241.     TransmitData(), FlushReceive()
  242.  
  243.    BUGS
  244. maestix.library/SetMaestro                         maestix.library/SetMaestro
  245.  
  246.    NAME
  247.     SetMaestro -- Sets the Maestro parameters (V35)
  248.  
  249.    SYNOPSIS
  250.     SetMaestro (^MaestroBase, ^Tags)
  251.             A0.l       A1.l
  252.  
  253.    FUNCTION
  254.     The card parameters are changed by the tags.
  255.  
  256.    INPUTS
  257.     MaestroBase     Pointer to MaestroBase Struct from AllocMaestro().
  258.     Tags            Tag list with the changes
  259.  
  260.    RESULTS
  261.  
  262.    TAGS
  263.     MTAG_Input      (ULONG) selects the input that shall be used.
  264.             Default is INPUT_STD, which is the input
  265.             selected by SetMstx. INPUT_OPTICAL and
  266.             INPUT_COAXIAL select the corresponding input.
  267.             INPUT_SRC48K selects the internal 48kHz source.
  268.  
  269.     MTAG_Output     (ULONG) selects the data source for the Maestro
  270.             output. Default is OUTPUT_BYPASS which leads
  271.             the incoming data directly to the output.
  272.             OUTPUT_INPUT decodes the input signal and
  273.             encodes it with new channel status bits and
  274.             user data bits. OUTPUT_FIFO encodes the trans-
  275.             ferred data to output.
  276.  
  277.     MTAG_SetCSB     (ULONG) The 32 bit will be put into the channel
  278.             status bits directly. This tag should be used
  279.             only exceptional.
  280.  
  281.     MTAG_SetUDB     (ULONG) The 32 bit will be put into the user
  282.             data bits.
  283.  
  284.     MTAG_Studio     (BOOL) The studio mode is selected if this
  285.             tag is TRUE, otherwise the custom mode is
  286.             selected. Defaults to FALSE.
  287.  
  288.     MTAG_CopyProh   (ULONG) CPROH_OFF turns the copy protection
  289.             off. CPROH_ON enables the copy protection,
  290.             but one single digital copy can be made.
  291.             CPROH_PROHIBIT turns the copy protection on;
  292.             the signal cannot be recorded. CPROH_INPUT
  293.             turns the copy protection on or off correspon-
  294.             ding to the input signal. Default is CPROH_OFF.
  295.  
  296.     MTAG_Emphasis   (ULONG) EMPH_OFF turns emphasis off. EMPH_50us
  297.             (= EMPH_ON) turns standard emphasis on. When
  298.             using studio mode, EMPH_CCITT and EMPH_MANUAL
  299.             can be selected, too. EMPH_INPUT chooses the
  300.             emphasis corresponding to the input signal.
  301.             Default is EMPH_OFF.
  302.  
  303.     MTAG_Source     (ULONG) selects the source category code.
  304.             Default is SRC_DAT. Other codes are SRC_DSR,
  305.             SRC_CD, SRC_ADCONV and SRC_INSTR. SRC_INPUT
  306.             selects SRC_DAT or SRC_CD, corresponding to
  307.             the input signal.
  308.  
  309.     MTAG_Rate       (ULONG) selects the rate. RATE_48000 is default,
  310.             RATE_44100, RATE_32000 and RATE_44100SUB are
  311.             possible, too. RATE_INPUT chooses a rate
  312.             corresponding to the input signal.
  313.  
  314.     MTAG_Validity   (BOOL) TRUE if the output signal is valid,
  315.             otherwise FALSE. Most receivers do not react
  316.             if MTAG_Validity is FALSE.
  317.  
  318.     MTAG_ResetUDB   If this tag occures, UDBs are reset and will
  319.             not be put out any more.
  320.  
  321.     MTAG_ResetLSA   This tag clears the local sample address which
  322.             is used in studio mode transfers only.
  323.  
  324.  
  325.    NOTES
  326.     Note that MTAG_Rate will only be transmitted in the channel
  327.     status bits and is completely independent to the rate that
  328.     Maestro uses for data transfer. Maestro is only capable to
  329.     generate a 48kHz rate (INPUT_SRC48K). If another rate is
  330.     required, it must be put to the choosen input.
  331.  
  332.     Some receivers do not accept the incoming signal if the
  333.     transmitted rate is not equal to the transfer rate.
  334.  
  335.     This function must be used from DOS process only!
  336.  
  337.    SEE ALSO
  338.  
  339.    BUGS
  340. maestix.library/TransmitData                     maestix.library/TransmitData
  341.  
  342.    NAME
  343.     TransmitData -- Transmits data from a message (V35)
  344.  
  345.    SYNOPSIS
  346.     TransmitData (^MaestroBase, ^Message)
  347.               A0.l         A1.l
  348.  
  349.    FUNCTION
  350.     The client has to fill out a DataMessage structure with a
  351.     reply port, a pointer to a data buffer and the size of this
  352.     buffer.
  353.  
  354.     This message is queued internally. If the transmitter has not
  355.     been started yet, this function will activate it.
  356.  
  357.     The buffer space will be put out and then be replied to the
  358.     declared reply port.
  359.  
  360.     If there are no more messages in the queue, the transmitter
  361.     will be stopped automatically, and an error is reported.
  362.  
  363.     The buffer contains signed words. The first word always belongs
  364.     to the left channel, the second to the right, and so on.
  365.  
  366.    INPUTS
  367.     MaestroBase     Pointer to MaestroBase Struct from AllocMaestro().
  368.     Message         Pointer to a system message with a pointer to
  369.             a buffer space for incoming data.
  370.  
  371.    RESULTS
  372.  
  373.    NOTES
  374.     The buffer space must be public memory. Its address must be
  375.     longword aligned and its length must be aligned to 1024.
  376.  
  377.    SEE ALSO
  378.     ReceiveData(), FlushTransmit()
  379.  
  380.    BUGS
  381.  
  382.